home *** CD-ROM | disk | FTP | other *** search
/ MACD 5 / MACD 5.bin / workbench / wb / czesc_1 / cerca / docs / cerca.doc next >
Text File  |  1992-11-27  |  19KB  |  730 lines
  1. ************************************************************************
  2. *                                                                      *
  3. *                               Cerca v1.1                             *
  4. *                            The File Finder                           *
  5. *                       (c) 1992 Carlo Todeschini                      *
  6. *                                                                      *
  7. ************************************************************************
  8.  
  9.  
  10. Introduction
  11. *************
  12.  
  13.  
  14. Motivation
  15. ===========
  16.  
  17.    When Amiga appeared first the only storing-device was the floppy with
  18. its 880k of space for datas: hard-drives, flopticals, CDs were unknown.
  19.  
  20.    Nowadays the situation is very different: the most recent Amigas come
  21. equipped with data storage units bigger than the original double-density
  22. drive...  the powerful A3000 comes with a hard-disk (from 50Mb to 100Mb
  23. inside, also the little A600 have an internal controller for IDE
  24. hard-drives (from 20Mb to 80Mb!), for 'older' models like A500 and A2000
  25. a great number of companies deliver different units, with different
  26. features and sizes... also the A1000 owners have hard drives now!
  27.  
  28.    With the increasing of the storage space, a lot of untidy users have
  29. been losing their files in the maze of directories, assignments, and
  30. devices made by themselves!!
  31.  
  32.    *"Where is that document? Where the picture? I'm sure they were
  33. here!! I can't find them... HELP!"*
  34.  
  35.    CERCA is made to scan a unit/path given by the user looking for a
  36. file-name or for a pattern, which indicates the matches with the full
  37. path. Besides CERCA can display some information on file found, like
  38. name, size, protection flags, date and file type from a list of about
  39. 70 types (*note Recognized file types::.), and it gives the opportunity
  40. to make operations on the indicated file simply by programming 4
  41. user-gadgets.
  42.  
  43.      *NOTE:* CERCA is the imperative form of the Italian verb
  44.      'cercare', whose meaning is 'to search'.
  45.  
  46.  
  47. Basics
  48. =======
  49.  
  50.    CERCA is a 2.04-only utility that tries to take advantage of some
  51. important features of the new system software (like pattern matching).
  52.  
  53.    *You can't use it under 1.x Amigas!*
  54.  
  55.    I drew the interface making it as simple as possible, all the
  56. functions have a key short-cut and the program offers a quite flexible
  57. configurability.
  58.  
  59.    CERCA is font sensitive: it uses the WorkBench font in whatever it
  60. makes.
  61.  
  62.    The program can also be run from Shell (dropping some
  63. functions...`:-(' ).
  64.  
  65.  
  66. Running
  67. ********
  68.  
  69.  
  70. Installation
  71. =============
  72.  
  73.    You can install CERCA by double clicking on the icon `Install.'
  74. CERCA needs two files to run:
  75.  
  76. `Cerca.config'
  77.      (not obligatory) that is the configuration file (I supply a file
  78.      for example in the archive). It must be placed in the `envarc:'
  79.      directory.
  80.  
  81. `Cerca.guide'
  82.      (not obligatory) that is the AmigaGuide(C) format of this
  83.      documentation (to view it press the help key). So, if you have the
  84.      library, you must set the environment variable `AmigaGuide/Path'
  85.      to search in the directory where `Cerca.guide' is placed. Open a
  86.      shell and type `SetEnv AmigaGuide/Path "S: Sys:My_Docs"'.
  87.  
  88.    Besides, if you want, you can enable ALL the pattern matching
  89. routines (e.g.: *, *.??, etc.) with `StarBurst', a program by W.G.J.
  90. Langeveld & Sebastiano Vigna that enables the * wildcard (you can find
  91. the program in the CERCA's archive).
  92.  
  93.  
  94. From Workbench
  95. ===============
  96.  
  97.    Couldn't be easier. Open the drawer where CERCA is placed in, double
  98. click on CERCA's icon and wait for the loading (Wow, which newness!!).
  99.  
  100.  
  101. From CLI
  102. =========
  103.  
  104.    You can run CERCA from CLI but in this manner you will lose some
  105. important features of the program. In fact the line command is
  106.  
  107.  
  108. `P=Pattern/A,D=Dir/A,F=Files/S,I=Dirs/S,B=Both/s,R=Root/S,X=Recursively/S'
  109.  
  110.    where:
  111.  
  112. `P=Pattern/A'
  113.      is the search pattern specified by wildcards (obligatory);
  114.  
  115. `D=Dir/A'
  116.      is the device/volume/assign where CERCA will search the file
  117.      (obligatory);
  118.  
  119. `F=Files/S'
  120.      is a switch to specify that you want to search only files;
  121.  
  122. `I=Dirs/S'
  123.      is a switch to specify that you want to search only dirs;
  124.  
  125. `B=Both/s'
  126.      is a switch to specify that you want to search both files and dirs;
  127.  
  128.           *Note:* Only one of the three switches above can be specified
  129.           or you will get an error!.
  130.  
  131. `R=Root/S'
  132.      is a switch to specify that you want to search only in the
  133.      directory specified with `Dir';
  134.  
  135. `X=Recursively/S'
  136.      is a switch to specify that you want to search for the file in all
  137.      the subdirectories of the one specified with `Dir';
  138.  
  139.           *Note:* Only one of the two switches above can be specified
  140.           or you will get an error!.
  141.  
  142.           If you don't specify any switch, CERCA uses the built-in
  143.           configuration: Files Recursively.
  144.      Examples:
  145.  
  146.     `Cerca #? SYS:'
  147.           Search all the files in the SYS: directory and in all of its
  148.           subdirectories;
  149.  
  150.     `Cerca #?.info Ram: F R'
  151.           Search all the files with `.info' as suffix only in the `Ram
  152.           Disk' directory;
  153.  
  154.     `Cerca Amiga dh2:data F'
  155.           Search the file `Amiga' in `dh2:data' and in all of its
  156.           subdirectories;
  157.  
  158.     `Cerca Amiga dh2: F I X'
  159.           Cerca will generate an error because you can't specify F and
  160.           I togheter.
  161.  
  162.  
  163. Using Cerca
  164. ************
  165.  
  166.  
  167. The interface
  168. ==============
  169.  
  170.    CERCA's interface presents three string fields, a list gadget with
  171. its scrollers and two banks of four buttons.
  172.  
  173.    * In the first field you can type the file to look for or the
  174.      pattern to use.
  175.  
  176.    * The next one displays the device/path you want to look in.
  177.  
  178.    * The last one contains the name (with path) of a file to operate on,
  179.      selected from the above list which presents all the found matches.
  180.  
  181.    * The first bank of buttons is that of CERCA actions:
  182.     `GO'
  183.           Start scanning the path indicated in `Path' gadget looking
  184.           for `File to search' contents.
  185.  
  186.     `STOP'
  187.           Abort the GO operation in any moment of the scan.
  188.  
  189.     `INFO'
  190.           Give information about the file selected in the listview.
  191.  
  192.     `SELECT'
  193.           Clicking on it a file requester will open. The path selected
  194.           will be inserted in the `Path' gadget and used in searching.
  195.  
  196.    The above four gadgets are customizable by the user: you can
  197. associate the program you want to each button (*note Settings Menu::.,
  198. for more info).
  199.  
  200.    CERCA has menus which reproduces every first bank action and permits
  201. you to configure the other four and to save/load the configuration file.
  202. CERCA's window is resizable, that means that if you drag the
  203. bottom-right border of it, it will resize on your favourite dimensions
  204. in any moment.
  205.  
  206.  
  207. Mouse Usage
  208. ============
  209.  
  210.    Using CERCA with the mouse isn't hard at all. The only thing you must
  211. do with the keyboard is typing the file pattern, the other operations
  212. have their button or menu to be activated.
  213.  
  214.  
  215. Keyboard Usage
  216. ===============
  217.  
  218.    Every CERCA action can be accessed by keyboard: the key short-cuts
  219. for actions are indicated in the buttons themselves by an underlined
  220. letter or in the relative menu.
  221.  
  222.    To activate the string fields press once the f key: the cursor will
  223. prompt in the `File to search' gadget, pressing Tab you will move to
  224. the next string-gadget, pressing Shift-Tab to the previous.
  225.  
  226.    By pressing the help key you'll invoke AmigaGuide(C) with this
  227. document displayed in hypertext. (`Cerca.guide' must be in your
  228. `envarc:AmigaGuide/Path' description).
  229.  
  230.  
  231. Menus
  232. ======
  233.  
  234.    Being an Amiga program, CERCA offers a couple of pulldown menus...
  235.  
  236.  
  237. Project Menu
  238. -------------
  239.  
  240. `Go'
  241.      Same as the `GO' button, will start the searching. (short-cut
  242.      RAmiga-G)
  243.  
  244. `Stop'
  245.      Same as the `STOP' button, will stop scanning the path. (short-cut
  246.      RAmiga-S)
  247.  
  248. `Info'
  249.      Same as the `INFO' button, will give information about the found
  250.      file. (short-cut RAmiga-I)
  251.  
  252. `Select'
  253.      Same as the `SELECT button', will open a requester to indicate the
  254.      path. (short-cut RAmiga-E)
  255.  
  256. `About'
  257.      Some information on the author and on the program.
  258.  
  259. `Quit'
  260.      Guess... (short-cut RAmiga-Q)
  261.  
  262.  
  263. Settings Menu
  264. --------------
  265.  
  266. `Search mode'
  267.      By this mutual exclude submenu you can establish the searching mode
  268.      of the program.
  269.  
  270.     `Only files'
  271.           to specify that you want to search only files;
  272.  
  273.     `Only dirs'
  274.           to specify that you want to search only dirs;
  275.  
  276.     `Both'
  277.           to specify that you want to search both files and dirs;
  278.  
  279.                *note:* Only one of the three menu items above can be
  280.                specified!
  281.  
  282.     `Only root'
  283.           to specify that you want to search only in the directory
  284.           specified in the `Search path' gadget;
  285.  
  286.     `All recursively'
  287.           to specify that you want to search the file in all the
  288.           subdirectories of the one specified in the `Search path'
  289.           gadget;
  290.  
  291.                *note:* Only one of the two menu items above can be
  292.                specified!
  293.  
  294. `Configure #n...'
  295.      (Where n is a number from 1 to 4)
  296.  
  297.      Opens a window with three string-gadgets: the first (`Command
  298.      name') contains the text that will be displayed in one of the four
  299.      custom buttons in the main window, the second is the program name
  300.      to run, to which CERCA passes a file name selected from the list
  301.      (for example if your command is `c:Delete', the resulting command
  302.      will be `c:Delete FILE_SELECTED_IN_THE_LISTVIEW'). The last one
  303.      contains the parameters for the console window.
  304.  
  305.      *Note:* The parameters of a console window are
  306.  
  307.      `CON:LeftEdge/TopEdge/Width/Height/Name/AUTO/CLOSE/WAIT/'
  308.  
  309.      `WINDOW 0XADDR/ SCREEN NAME, etc'
  310.  
  311.      where the last five optional keywords means:
  312.  
  313.     `AUTO'
  314.           don't open CON: window until/unless input or output occurs;
  315.  
  316.     `CLOSE'
  317.           put a close gadget om the CON: window;
  318.  
  319.     `WAIT'
  320.           hold off close until user clicks `Close' or types `CTRL-\';
  321.  
  322.     `WINDOW'
  323.           Use specified window (may be on a custom screen);
  324.  
  325.     `SCREEN'
  326.           Open on specified public screen;
  327.  
  328.     `'
  329.           The additional `CON:' keywords `BACKDROP, NODRAG, NOBORDER,
  330.           NOSIZE, SIMPLE,' and `SMART', allow control of other
  331.           attributes of a CON: window.
  332.  
  333.      `Example: "CON:0/0/640/256/My console/AUTO/CLOSE/WAIT".'
  334.  
  335.      If the `Run Asynch.' gadget is checked you establish that your
  336.      command will be run in asynchronous mode so you can quit CERCA
  337.      even if your program is running and you can continue working with
  338.      it! :-).
  339.  
  340.      If the `Open Console' gadget is checked you establish to open an
  341.      I/O console (read above) for your application.
  342.  
  343.      The `Select' gadget helps you to find your program by a file
  344.      requester and will place the command in the `Function' gadget.
  345.      Click `Ok' to confirm your settings or `Cancel' to forget them.
  346.      (short-cut `RAmiga-N', with N from 1 to 4)
  347.  
  348. `Open Settings...'
  349.      Will load a configuration previously saved with `Save Settings' or
  350.      `Save Settings As...'.
  351.  
  352. `Save Settings'
  353.      Will save actual string-gadgets' and buttons' content, search mode
  354.      configuration  and actual window's position and dimension in the
  355.      file `Cerca.config' in the `envarc:' directory.
  356.  
  357. `Save Settings As...'
  358.      Same as the above menu, but here you can select another name and
  359.      dir for the configuration file.
  360.  
  361.  
  362. Appendices
  363. ***********
  364.  
  365.  
  366. Pattern matching under 2.0
  367. ===========================
  368.  
  369.    The `dos.library v37' (or greater) contains new functions to parse
  370. an argument string and to evaluate it. By default search patterns are
  371. `? # % ' ,' and  after installing StarBurst (or equivalent) you find
  372. added `*'. There are some operators which can be used to bind two or
  373. more patterns (a multi-pattern): they are `~ | ( )'.
  374.  
  375.    There are some examples:
  376.  
  377. `Pattern'
  378.      Meaning
  379.  
  380. `?'
  381.      Matches any single character
  382.  
  383. `#<C>'
  384.      Matches the <C> item occurring zero or more times
  385.  
  386. `%'
  387.      Like a null string (same as  giving a "" file name as parameter to
  388.      a command)
  389.  
  390. `#? or *'
  391.      Matches any string
  392.  
  393. `''
  394.      Remove the effect of the pattern character
  395.  
  396. `Operator'
  397.      Logical Meaning
  398.  
  399. `|'
  400.      or
  401.  
  402. `( )'
  403.      and
  404.  
  405. `~'
  406.      not
  407.  
  408.    Examples:
  409.  
  410. `Delete #?'
  411.      Will delete all the contents of the actual path
  412.  
  413. `Delete #?.info'
  414.      Will delete any file ending with the string `.info' and starting
  415.      with any combination of any lenght of characters
  416.  
  417. `Delete ~(#?.info)'
  418.      Will delete any file which doesn't end with `.info'
  419.  
  420. `Dir *.pic'
  421.      Displays all the files ending with `.pic' (same as #?.pic)
  422.  
  423. `Dir (*.pic|*.iff)'
  424.      Displays all the files ending with `.pic' or `.iff'
  425.  
  426. `CD Sheet'#'
  427.      If it exists, the system will assume it as actual directory
  428.      `Sheet#'
  429.  
  430. `Dir CG*'
  431.      Displays all the files starting with `CG'
  432.  
  433. `Dir CG*fonts'
  434.      Displays all the files starting with `CG' and ending with `fonts'
  435.  
  436.    For more information about the argument read the manual *Using The
  437. System Software* chapter *AmigaDos References*, (c) 1990/1991 by
  438. Commodore Amiga Inc.
  439.  
  440.  
  441. Recognized file types
  442. ======================
  443.  
  444.    CERCA can recognize a lot of file types (listed below):
  445.  
  446.    * Workbench icon file
  447.  
  448.    * ASCII text file
  449.  
  450.    * 'C' source code file
  451.  
  452.    * 'C' header file
  453.  
  454.    * Assembly language source code file
  455.  
  456.    * Assembly language include file
  457.  
  458.    * Modula-2/Oberon source code file
  459.  
  460.    * ARexx script file
  461.  
  462.    * Basic source code
  463.  
  464.    * AmigaGuide(C) document file
  465.  
  466.    * TeX document file
  467.  
  468.    * Metafont font file
  469.  
  470.    * Generic font file
  471.  
  472.    * Packed TeX font file
  473.  
  474.    * TeX device independent output file
  475.  
  476.    * PasTeX font library file
  477.  
  478.    * Manx 3.x object code file
  479.  
  480.    * Manx 5.x object code file
  481.  
  482.    * Manx 3.x library file
  483.  
  484.    * Manx 5.x library file
  485.  
  486.    * AmigaDOS object code file
  487.  
  488.    * AmigaDOS object code library file
  489.  
  490.    * AmigaDOS executable file
  491.  
  492.    * System library file
  493.  
  494.    * System device file
  495.  
  496.    * AmigaDOS filing system handler file
  497.  
  498.    * AmigaDOS handler file
  499.  
  500.    * GIF image file
  501.  
  502.    * Degas image file
  503.  
  504.    * MacPaint image file
  505.  
  506.    * SuperPaint image file
  507.  
  508.    * Macintosh PICT image file
  509.  
  510.    * Sun raster image file
  511.  
  512.    * Postscript file
  513.  
  514.    * PCX image file
  515.  
  516.    * TIFF image file
  517.  
  518.    * Windows bitmap image file
  519.  
  520.    * JFIF image file
  521.  
  522.    * IFF-ILBM image file
  523.  
  524.    * IFF-ANIM animation file
  525.  
  526.    * IFF-8SVX sound file
  527.  
  528.    * IFF-SMUS score file
  529.  
  530.    * IFF-FTXT text file
  531.  
  532.    * IFF-PREF preferences file
  533.  
  534.    * IFF-TERM `term' configuration file
  535.  
  536.    * IFF file
  537.  
  538.    * AmigaVision flow file
  539.  
  540.    * Imploder data output file
  541.  
  542.    * PowerPacker data output file
  543.  
  544.    * LhPak self extracting archive
  545.  
  546.    * LhASFX self extracting archive
  547.  
  548.    * Arc archive file
  549.  
  550.    * ARJ archive file
  551.  
  552.    * Compress output file
  553.  
  554.    * CPIO archive file
  555.  
  556.    * Freeze output file
  557.  
  558.    * MacCompress archive file
  559.  
  560.    * Compact archive file
  561.  
  562.    * Diamond archive file
  563.  
  564.    * LhArc archive file
  565.  
  566.    * LHA archive file
  567.  
  568.    * Zoo archive file
  569.  
  570.    * PKZip archive file
  571.  
  572.    * Stuff It! archive file
  573.  
  574.    * Pack It! archive file
  575.  
  576.    * DMS disk archive file
  577.  
  578.    * Warp disk archive file
  579.  
  580.    * Zoom disk archive file
  581.  
  582.    * SPARC object code
  583.  
  584.    * SPARC executable
  585.  
  586.    * MS-DOS executable
  587.  
  588.    * Atari-ST/TT executable
  589.  
  590.    * Macintosh executable
  591.  
  592.    I think they should be enough `;-)' !!!
  593.  
  594.  
  595. To Do
  596. ======
  597.  
  598.    Here are some plans for future expansion of CERCA. Comments and
  599. additions are welcome.
  600.  
  601.    * Becoming a commodity: resident, little, with a key pop-up.
  602.  
  603.    * Configurable list of most used patterns.
  604.  
  605.    * Possibility to iconify the program.
  606.  
  607.    * Multiple dir/volume search.
  608.  
  609.    * Localization.
  610.  
  611.    * Arexx port to communicate with other applications.
  612.  
  613.    ... to be continued ...
  614.  
  615.  
  616. Known Bugs
  617. ===========
  618.  
  619.    The actual version (37.75) was tested very hardly with `Enforcer'
  620. and `Mungwall' for a long time. If you find a bug, please contact me.
  621.  
  622.  
  623. History
  624. ========
  625.  
  626.    * CERCA V1.0 (37.69)  :  First release.
  627.  
  628.    * CERCA V1.1 (37.75)  :  Now, the configuration file is saved in
  629.      `envarc:Cerca.config' instead of `S:Cerca.config'. Note that the
  630.      old configuration file is still good.
  631.  
  632.      Fixed a bug when opens a window with small fonts (like topaz 8-9).
  633.      Now works with all fonts.
  634.  
  635.      Fixed a bug when loads a configuration more 'large' then the
  636.      actual selected. Now the window will modify their dimensions.
  637.  
  638.      Now AmigaGuide(C) is not necessary to run the program. However, if
  639.      you have the library, you must now set the environment variable
  640.      `AmigaGuide/Path' to search in the directory where `Cerca.guide'
  641.      is placed. Open a shell and type `SetEnv AmigaGuide/Path "S:
  642.      Sys:My_Docs"'.
  643.  
  644.      Now the menus are compatible with the NewLookMenus of OS 3.0
  645.      (black pen on white background).
  646.  
  647.      Now Cerca's error messages appear on the workbench window.
  648.  
  649.  
  650. Greetings
  651. ==========
  652.  
  653.    Finally, I want to thank
  654.  
  655.    * Finardi Dario for suggestions, first & hard testing and part of the
  656.      manual.
  657.  
  658.    * Barthel Olaf (the author of 'Term') for the base utility of the
  659.      file type identification.
  660.  
  661.    * Vigna Sebastiano for suggestions and beta testing.
  662.  
  663.    * Puerari Monia for the revision of this English manual.
  664.  
  665.    * Reinhard Spisser for converting the documentation in TeXinfo
  666.      format.
  667.  
  668.    * Di Giuseppe Fabrizio for the beautiful icon.
  669.  
  670.    * The beta testers: Attias Roberto, Gentile Giovanni, Lodi Fabrizio,
  671.      Ruocco Sergio, Santagostino Carlo, Silvera Paolo, Zandonadi Marco.
  672.  
  673.  
  674. The Documentation
  675. ==================
  676.  
  677.    The documentation files for CERCA are given in four different
  678. formats:
  679.  
  680. `Cerca.doc'
  681.      The documentation for CERCA in ASCII;
  682.  
  683. `Cerca.guide'
  684.      The documentation for CERCA in AmigaGuide. hypertext format;
  685.  
  686. `Cerca.dvi'
  687.      The documentation for CERCA in TeX's device-independent format;
  688.  
  689. `Cerca.texinfo'
  690.      The documentation for CERCA in TeXinfo format; using `makeinfo'
  691.      you can produce the `.doc' and `.guide' files.
  692.  
  693.  
  694. Program and distribution notes
  695. ===============================
  696.  
  697.    CERCA is (C) 1992 Carlo Todeschini and it's freely distributable as
  698. long as all of its files are included in their original form without
  699. additions, deletions, or modifications of any kind, and only a nominal
  700. fee is charged for its distribution.
  701.  
  702.    CERCA is a *DonationWare* program. If you like and so use CERCA,
  703. make a donation to a public institution or foundation like *Fight
  704. Against Cancer*, *WWF*, *Amnesty International*, *UNICEF* etc...and
  705. write me to tell that you like my work.
  706.  
  707.    This software is provided "AS IS" without warranty of any kind,
  708. either expressed or implied. By using CERCA, you accept either the
  709. whole risk or the quality and performance of the program.
  710.  
  711.  
  712. How to reach the author
  713. ========================
  714.  
  715.    If you have some additional ideas and/or bug reports, feel free to
  716. send a letter (e-mail preferred) or to give me a call (you're advised:
  717. letters or e-mail costs less `:-)').
  718.  
  719.    You can reach me via
  720.  
  721.  
  722.       Internet: todeschi@pippo.sm.dsi.unimi.it
  723.  
  724.           Mail: Carlo Todeschini
  725.                 via Martiri della Liberta' 25
  726.                 I-26030 Malagnino (CR)
  727.  
  728.          Phone: +39-(0)372-58171
  729.  
  730.